Jump to content

Security Features-Qualcomm TEE

From RidgeRun Developer Wiki


Follow us on: YouTube Twitter LinkedIn Email Share this page

Share This Page

Qualcomm Dragonwing Technical Guide logo
Qualcomm Dragonwing Technical Guide

Qualcomm Dragonwing Technical Guide
Table of Contents [Sticky]




Introduction

The Qualcomm Trusted Execution Environment (TEE) is a software implementation that runs within the Arm TrustZone environment on the Dragonwing IQ-9075. The TrustZone is a hardware-based security architecture enabled through a Secure mode of the Arm processor. It establishes two execution environments with hardware-enforced isolation across the entire system. Qualcomm offers a 64-bit Armv8.x processor system with hardware virtualization to run TrustZone. There are two different security states implemented in this architecture:

  • Secure: Qualcomm TEE and trusted applications operate in this state.
  • Non-secure: Linux operates in this mode of the Arm core.


Info
For more information, please visit our Platform Security Manual/TEE


The Secure mode is the core concept behind TrustZone and its architecture. Its exception levels and their key components are:

Exception Level Secure Mode Non-Secure Mode
EL0 Qualcomm TEE
and Trusted Applications 		Linux user space:
  • Mink
  • Key management
  • Client application
EL1 Qualcomm TEE Mink Linux kernel space:
  • QCOMTEE driver
  • Cryptographic driver
EL2 - Qualcomm Hypervisor
EL3 Secure Monitor -

The system can operate either in a secure or non-secure state at exception levels EL0, EL1, and EL2, while EL3 will always run in the secure state.

Exception Level 0

Non-Secure mode

This user space includes the primary security modules in the Linux user space, such as:

  • Mink-Linux
    • Provides services and serves as the transport mechanism to use the Qualcomm TEE capabilities through trusted applications.
    • Provides system listener services, intended as an extension to Qualcomm TEE functionality.
    • Implements the global platform TEE client APIs for running global platform-based trusted applications through libGPTEEC and libMTEEC libraries.
    • Implements client applications in the Linux user space and interacts with TAs that operate in the Qualcomm TEE. This may include:
      • Client application developed using mink APIs
      • Global platform-based client application
      • Client application developed using the global platform-based TEE client API specification.
  • Key management:
    • libckteec cryptographic library, which interfaces with the PKCS#11 interface of TEE. User space applications running on Linux can use this library for direct access to the PKCS#11 interface.
    • The libckteec library also defines the interface between an application and a cryptographic device. This means cryptographic devices can be treated as tokens by the application and can perform cryptographic functions as implemented by these tokens.
    • There are multiple cryptographic services for encryption, decryption, signature generation, signature verification, and permanent key storage provided by the PKCS#11 interface.

Secure mode

The Qualcomm TEE SDK runs at this level. Qualcomm offers this software development kit to build and develop trusted applications. The SDK already includes the necessary build system, header files, and library dependencies to compile trusted applications.

Trusted Applications

Trusted applications (TA) offer services within a secure environment for Linux clients operating in the non-secure world. Qualcomm TEE adds services to TAs such as:

  • Support for TAs to operate in EL0 secure mode: Trusted Applications run in Secure EL0 (user mode), providing isolation from the secure kernel while still accessing secure services through controlled interfaces.
  • Sand-boxing environment for TAs: Trusted Applications execute in isolated environments that prevent direct access to other TAs' memory or resources. Communication with other authorized TAs is still possible through secure inter-TA mechanisms such as QTEE IPC.
  • Position-independent loading of TAs: Trusted Applications are loaded independently of a fixed memory address, allowing the secure loader to place them anywhere within the allocated secure memory region.
  • Message passing between different TAs: Trusted Applications can securely invoke services exposed by other TAs entirely within the secure world, without passing through the non-secure operating system.

TAs operate from hardware-protected memory. However, the applications that require more memory can use double data rate (DDR) memory for loading and running. TAs are set to run from hardware-protected memory by default.

Exception Level 1

Non-Secure mode

The EL1 non-secure mode provides security-specific kernel drivers for the Linux kernel space, such as:

  • QCOMTEE driver:
    • The driver extends the subsystem's functionality to support the Qualcomm-specific requirements, although, is also integrated into the standard Linux TEE subsystem.
    • The driver source is located at drivers/tee/qcomtee/.
    • The driver identifier value for QCOMTEE within the TEE subsystem is typically 3, a unique value to differentiate it from the OP-TEE(1) and the AMD-TEE(2).
    • The QCOMTEE driver has a mink IPC layer on top of it, as the standard TEE subsystem does not support object-based IPC natively. This introduces generic object abstractions that can be referenced using specific IOCTLs.
    • Communication architecture:
      • User space: Applications use the MTEEC (mink TEE client) library or minkipc to interact with objects.
      • TEE Subsystem: The use of standard IOCTLs is implemented as long as possible, as new IOCTLs are implemented in order to handle object-specific logic.
      • QCOMTEE Driver: It translates and packages Linux-side arguments into a format compatible with the Qualcomm Trusted Execution Environment (QTEE).
      • Qualcomm TEE: Receives requests and executes TA logic as requested.

Secure mode

The Qualcomm TEE mink is responsible for the message passing across different domains such as the kernel domain or the user domain. Software may run in one or more communicating domains, requiring code execution to invoke objects located in a different domain. These domains vary in their ability to access memory and other system resources:

  • The kernel domain executes at secure EL1 and has complete control over the system resources.
  • The user domains run at secure EL0 and have restricted access to system resources.

The Qualcomm TEE mink allows for precise control over the access granted to a process.

Exception Level 2

Non-Secure mode

The Qualcomm Hypervisor runs at this level, a modern virtualization framework that allows multiple operating systems to run independently and concurrently, with high performance. It also enables the hosting of multiple TEEs for secure use cases. The Qualcomm Type-1 Hypervisor provides the following features:

  • Enhanced security compared to Type-2 (hosted) hypervisors.
  • Multi-core, real-time operations independent of Linux.
  • Operates independently and with higher privileges than Linux
  • Minimal impact on performance.

Secure mode

There is not a secure mode app specifically for this level, yoy can see more information on Qualcomm's Official documentation.

Exception Level 3

Secure mode

The Secure Monitor runs at this level, a component of TrustZone that is responsible for the transitions between secure and non-secure modes. It operates in Monitor mode, which can be activated from a privileged Arm mode. It also ensures correct context saving and restoration when switching between the non-secure and secure modes. Additionally, it handles the initial processing of secure interrupts.

Security APIs

Trusted and client applications can be developed and executed using the default files provided by the GlobalPlatform interface. Trusted applications run within the Trusted Execution Environment (TEE), where they benefit code and data integrity and protection. In contrast, client applications execute in the normal operating system and interact with trusted applications through TEE client APIs to access secure services. This feature is available to licensed developers with authorized access to develop and execute trusted applications and client applications. If you have access, see Qualcomm's Official Documentation for more information.

For development involving hardware-backed attestation, zero-touch device provisioning, or management of chipset-specific features, Qualcomm provides additional support through the Qualcomm Linux Wireless Edge Services. This feature is available to licensed developers with authorized access. If you have access, see Qualcomm's Official Documentation for more information.

The security APIs provide the possibility of interacting with both the Linux kernel and underlying hardware components. They also enable access to a range of software services that can operate within a Trusted Execution Environment (TEE). The available APIs are:

  • User-Space API: provide the interface through which the Linux operating system communicates with kernel-level functionality. This feature is available to licensed developers with authorized access. If you have access, see Qualcomm's Official Documentation for more information.
  • Kernel APIs: provide interaction between Qualcomm Linux software and device hardware.
  • Cryptographic APIs: The qcrypto.ko driver is located at /lib/modules/<version>/kernel/drivers/crypto/qce enabling kernel-level and user-level APIs to access the crypto engine. For APIs, see the kernel crypto documentation. The supported cryptographic algorithms are supported
    • RFC 4309 (CCCM (AES))
    • CCM (AES)
    • Authenc (HMAC (SHA-256), CBC (AES))
    • Authenc (HMAC (SHA-256), CBC (DES3_EDE))
    • Authenc (HMAC (SHA-256), CBC (DES))
    • Authenc (HMAC (SHA-1), CBC (DES3_EDE))
    • Authenc (HMAC (SHA-1), CBC (DES))
    • HMAC (SHA-256)
    • HMAC (SHA-1)
    • SHA-256
    • SHA-1
    • CBC (DES3_EDE)
    • ECB (DES3_EDE)
    • CBC (DES)
    • ECB (DES)
    • XTS (AES)
    • CTR (AES)
    • CBC (AES)
    • ECB (AES)
  • Hardware random generator APIs: provide support for a true random number generator (TRNG) through the qcom-rng Linux driver. This driver integrates with the kernel cryptographic framework to supply random data via the kernel's random number generation APIs. In user space, applications can access hardware-generated random numbers through the /dev/hwrng device interface. This feature is available to licensed developers with authorized access. If you have access, see Qualcomm's Official Documentation for more information.
  • Qualcomm TEE APIs: Qualcomm TEE includes a set of APIs that provide essential services for secure applications operating within the Trusted Execution Environment. These APIs support capabilities such as memory allocation and management, logging, secure storage access, communication with listeners, and a variety of cryptographic and hashing operations. This feature is available to licensed developers with authorized access. If you have access, see Qualcomm's Official Documentation for more information.


Configuring Qualcomm TEE

Maintaining the security, compliance, performance, and flexibility of devices that manage sensitive data and run trusted applications requires proper Qualcomm TEE configuration. These configurations are adjusted through the device configuration (devcfg) framework, which provides a centralized mechanism for managing device-specific settings.

Compile devcfg image from TrustZone

The TrustZone sources are included in within the firmware source components for the Qualcomm Linux 1.8 installation guide. The TrustZone sources will be found in the following path (Refer to the Qualcomm Linux 1.8 Build Guide to see which firmware distributions are available):

Info
Adjust the directory path as needed.
export FIRMWARE_ROOT=$HOME/firmware-dir/
export FIRMWARE_DISTRO=<your-distro-of-choice>
$FIRMWARE_ROOT/$FIRMWARE_DISTRO

1. Select your desired TrustZone version. For this guide, the TZ.XF.5.29.1 version will be used, but you can modify the command with the correspondent version: 

export TRUSTZONE_PATH=$FIRMWARE_ROOT/$FIRMWARE_DISTRO/TZ.XF.5.29.1

2. Select the desired configuration options that TrustZone offers through the built-in devcfg.mbn XML files. For example, $TRUSTZONE_PATH/trustzone_images/ssg/securemsm/trustzone/qsee/mink/oem/config/lemans/oem_config.xml. The full list of configuration parameters is mentioned later in this wiki.

3. The devcfg_iot.mbn file is not generated by default. Apply the following patch to the $TRUSTZONE_PATH/trustzone_images/build/ms/build_config_deploy_lemans.xml file to generate it: 

trustzone_images/build/ms/build_config_deploy_lemans.xml
@@ -60,9 +60,12 @@
<alias build-once="false" disable="false" internal-test="false" recompile="true" strip="false" name="devcfg_auto_sgvm">
<artifact name="devcfg_auto_sgvm"/>
</alias>
+  <alias build-once="false" disable="false" internal-test="false" recompile="true" strip="false" name="devcfg_iot">
+  <artifact name="devcfg_iot"/>
+  </alias>

4. Compile the devcfg image from TZ.XF.5.29.1: 

cd $TRUSTZONE_PATH/trustzone_images/build/ms
export SECTOOLS=$FIRMWARE_ROOT/$FIRMWARE_DISTRO/QCS9100.LE.1.0/common/sectoolsv2/ext/Linux/sectools
python3 build_all.py -b TZ.XF.5.0 CHIPSET=lemans devcfg_iot --cfg=build_config_deploy_lemans.xml

This step generates the devcfg.mbn images at $TRUSTZONE_PATH/trustzone_images/build/ms/bin/MAKAANAA, build flavor corresponding to the Dragonwing IQ-9075.


Warning
The steps moving forward have not been verified by the RidgeRun team and were extracted from the Official QDL Documentation. Please be aware of this when following this guide.


5. Replace the devcfg_iot.mbn file located at $WORK_DIR/build-qcom-wayland/tmp-glibc/deploy/images/qcs9075-iq-9075-evk/ with the generated devcfg_iot.mbn binary with the selected TrustZone options.

6. Flash the device configuration binary alongside all other binaries to the device following the Flashing an Image Guide.

Configuration parameters

Use the configuration parameters listed in the following table to customize the device as needed.

Configuration parameter Description
OEM_pil_secure_app_load_region_size Customizes the TA load region size. Must remain synchronized with the memory map used by TrustZone; otherwise TA loading may fail.
OEM_pil_subsys_load_region_start Customizes the PIL image load start address when the default memory map is modified.
OEM_pil_subsys_load_region_size Customizes the PIL image load region size when the default memory map changes.
OEM_enable_app_fatal_err Forces a TrustZone system fatal error when a specified trusted application crashes.
OEM_crash_ta_name Specifies the TA name whose crash should trigger a secure kernel crash. Can be configured as * to trigger on any TA crash.
OEM_sec_wdog_bark_time Configures the secure watchdog bark timeout.
OEM_sec_wdog_bite_time Configures the secure watchdog bite timeout.
OEM_tz_log_level Sets the TrustZone logging level: Fatal (0), Error (1), Debug (2).
OEM_allow_rpmb_key_provision Allows RPMB key reprovisioning when storage devices are replaced. Should remain disabled on production devices.
OEM_disable_rpmb_autoprovisioning Enables or disables automatic RPMB production key provisioning.
OEM_reset_reason_list Allows OEMs to extend the list of reset reasons reported by the system.
OEM_app_sandbox_default Enables TA sandboxing and requires third-party TAs to be authenticated using an OEM-provided root certificate.
OEM_enablecrashdumps_before_arb Enables crash dump generation when anti-rollback fuses have not yet been blown.
OEM_pub_mod RSA public key modulus used for TrustZone log encryption.
OEM_pub_exp RSA public key exponent used for TrustZone log encryption.
OEM_log_encr_enable Enables or disables encrypted TrustZone diagnostic and QSEE log collection.
OEM_MRC_activation_list Defines fuse values used to select the active root certificate index for MRC-signed images.
OEM_MRC_revocation_list Defines fuse values used to revoke root certificate indices for MRC-signed images.
OEM_counter_measure_enable Enables timing countermeasures intended to mitigate side-channel attacks.
OEM_Blacklisting_TA_auth_type Blocks TAs from loading based on their authentication type (OEM, ALT, or both).
OEM_Blacklisting_TA_cert_id Blocks TAs from loading based on certificate identifiers.
OEM_enable_bootup_from_a_b_partition Enables support for Android A/B system updates and anti-rollback handling across A/B partitions.
OEM_disable_scattered_memory Disables scattered memory support for large TAs, favoring performance over fragmentation resilience.
OEM_wdog_flags Enables user-level watchdog functionality for trusted applications.
OEM_wdog_ms_initial Specifies the watchdog timeout for a TA thread to become ready to accept requests.
OEM_wdog_ms_accept_hlos Specifies the watchdog timeout for processing requests in a normal HLOS environment.
OEM_wdog_ms_accept_uefitzt Specifies the watchdog timeout for processing requests in a UEFI-TZT environment.

It is important to note that the OEM_log_encr_enable option is important to debug TEE with secure boot. The next steps are to enable secure boot ensuring only trusted applications run on the device and flashing the device with the secure images. You can follow the guide on the Secure Boot wiki for more information.

Qualcomm Dragonwing Technical Guide logo
Qualcomm Dragonwing Technical Guide
Back to top ↑

Retrieved from "https://developer.ridgerun.com/wiki/index.php?title=Qualcomm_Dragonwing_Technical_Guide/Security_Features/TEE&oldid=84134"
Cookies help us deliver our services. By using our services, you agree to our use of cookies.